home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / ngs_10.zip / NGS.DOC < prev    next >
Text File  |  1994-05-13  |  11KB  |  246 lines
  1.              ┌───────────────────────────────────────────────────┐
  2.              │                                                   │
  3.              │            Norton Guides Sourcer (NGS)            │
  4.              │                    version 1.0                    │
  5.              │                   DOCUMENTATION                   │
  6.              │                                                   │
  7.              └───────────────────────────────────────────────────┘
  8.  
  9.  
  10.  1. Copyright
  11.     ═════════
  12.     Norton Guides Sourcer (NGS) and its documentation are:
  13.  
  14.     Copyright 1994, by Kemal Djakman (the author).
  15.  
  16.     NGS can be copied and distributed freely for any non-commercial purposes,
  17.     as long as the program NGS.EXE and its accompanying documentation NGS.DOC
  18.     are distributed together unmodified.  Archiving the above mentioned files
  19.     into ZIP, ARJ, etc. to save storage space is hereby allowed.
  20.  
  21.     No payment whatsoever is required for the use of NGS either by private
  22.     individuals or by companies/institutions; but NGS may only be incorporated
  23.     into a commercial software with the express written permission from the
  24.     author.
  25.  
  26.     Warranty
  27.     ════════
  28.     The author makes no warranty of any kind, neither express or implied,
  29.     including without limitation, any warranties of merchantability and/or
  30.     fitness for a particular purpose.  The author shall not be liable for
  31.     any damages, whether direct, indirect, special or consequential arising
  32.     from a failure of this program to operate in the manner desired by the
  33.     user.  The author shall not be liable for any damage to data or property
  34.     which may be caused directly or indirectly by use of the program.
  35.  
  36.  
  37.  2. Introduction
  38.     ════════════
  39.     a. What is NGS ?
  40.  
  41.     NGS is a re-sourcer for Norton Guides Database (*1*).  It processes a
  42.     Guides database file (an .NG file) and tries to recreate the sources.
  43.  
  44.     b. Why would anybody need a Guides (re)-sourcer ?
  45.  
  46.     Three possibilities comes to my mind:
  47.     - To do away with the need to have a backup of the original sources.
  48.     - You have a Guides Database which needs to be updated or corrected,
  49.       for which you don't have the sources.
  50.     - You want to convert a Guides database into another format.
  51.  
  52.     *IMPORTANT*
  53.     NGS are not meant to encourage the stealing of somebody elses property!
  54.     When re-sourcing a Guides database which is created by somebody else,
  55.     do not redistribute them as if it was your own!  Always maintain the
  56.     credits of the original creator!
  57.  
  58.     c. Why NGS?
  59.  
  60.     Although there are already several sourcer available for Norton Guides
  61.     Databases, none that I have tried works without a problem.  Some of
  62.     them does not handle !seealso references to another file, or does not
  63.     recreate the '!credits' entry.  Others have problem with nested short
  64.     lists or long entry included via the !file command.  Some crashed or
  65.     even goes into infinite-loop, etc.
  66.  
  67.     Because of a personal need to update a Guides database to which I have
  68.     lost the sources, I decided to write my own sourcer from scratch.
  69.  
  70.     d. What is so special about NGS ?
  71.  
  72.     Binary Equality (tm): When re-sourcing an .NG file, NGS will do it in
  73.     such a way that when the sources are recompiled into an .NG file, the
  74.     new file will be equal with the old one: It will be exactly the same,
  75.     byte for byte (*2*).  This is the only sure fire method to verify the
  76.     correctness of the generated sources!
  77.  
  78.     (NGS is also _very_ fast, although this property is probably not very
  79.     important to the average user.)
  80.  
  81.  
  82.  3. Requirement
  83.     ═══════════
  84.  
  85.     A personal computer with i286+ processor running DOS v3.3 or later with
  86.     at least 256Kb of free RAM and available disk space of about 150% of the
  87.     size of the .NG file to be resourced.
  88.  
  89.     Additionally, if recompilation into .NG file is intended, the programs
  90.     MAKE.EXE and NGC.EXE + NGML.EXE (from Peter Norton Computing, Inc.).
  91.  
  92.  
  93.  4. Usage
  94.     ═════
  95.     Using NGS is quite simple.  At the DOS prompt, just type 'NGS' followed
  96.     by the filename of the NG database to be re-sourced.  For example:
  97.  
  98.       C:\>ngs qedit
  99.  
  100.     In the above example, NGS will look on the current drive and path for a
  101.     file named QEDIT.NG and create the data source files.
  102.  
  103.     The full syntax of NGS invocation is:
  104.  
  105.        NGS [d:][path]filename[.NG] [/M] [/V] [>logfile]
  106.  
  107.     Notes:
  108.     - The .NG extension is optional, but no other extension is allowed.
  109.     - The output of NGS can be redirected using DOS stdout redirection.
  110.     - All files created by NGS will reside on the current drive and directory.
  111.  
  112.     Meaning of the command line options:
  113.     /M    Create file with the name 'MAKEFILE' instead of '<filename>.MAK'
  114.           Some user might prefer this (although this is easy to rename).
  115.     /V    Verbose mode.  Display the begin offset of each structure processed.
  116.           Use this to see on which structure an error or warning occurred. Can
  117.           also be used to make it possible to stop the running of the program
  118.           by pressing Ctrl-Break key sequence.
  119.  
  120.  
  121.  5. Files created by NGS
  122.     ════════════════════
  123.     filename.mak --> Makefile to compile the sources back into NG file
  124.     filename.ngm --> Menu Link Control File
  125.     finameXX.ngs --> Data Source File for each menu item in Menu Link Control
  126.                      File.  Filename is created by concatenating a maximum of
  127.                      6 chars from the basename and a 2 digits signifying menu
  128.                      number and item number (0 based).
  129.     L_XXXXXX.ngs --> Long Entry Data Source File for each long entry included
  130.                      via the '!file:' bang command.  The hex digits correspond
  131.                      with structure offset in the original NG file.
  132.     S_XXXXXX.ngs --> Short Entry Data Source File for each nested short entry
  133.                      specified using the '!file:' bang command.
  134.  
  135.  
  136.  6. NGS warning messages
  137.     ════════════════════
  138.     A warning means that an error was detected by NGS in the database, but
  139.     it is not severe enough to cause NGS to stop sourcing the database.
  140.     The user might later try to rectify the error by modifying the sources.
  141.  
  142.     1. Warning: Seealso does not point to another Long entry
  143.          NGS has found a seealso entry which point to a structure other
  144.          than a long entry.  This might be caused by a corrupted NG file,
  145.          or it is an NG file created by other than Norton Guides Compiler.
  146.  
  147.     2. Warning: Seealso "xxxxxxxx" reference is unresolved
  148.          NGS has found a seealso title which points to nowhere.  This
  149.          usually happens when the original source has a !seealso which
  150.          refers to an empty short entry or a non-existing short item.
  151.  
  152.     3. Warning: NG binary equality might not be achieved
  153.          NGS has seen that the current menu structure has the maximum 8 menu
  154.          items under it.  Because of a bug in NGML.EXE, certain location
  155.          in the .NG file will have part of the first menu item filename.
  156.          This results in differences of up to 6 bytes between the original
  157.          .NG file and the new recompiled .NG file.
  158.  
  159.     4. Warning: structure does not end with "0"
  160.          Each menu structure should be terminated with a null byte.
  161.          This might be caused by a corrupted NG file.
  162.  
  163.  
  164.  7. NGS error messages
  165.     ══════════════════
  166.     An NGS error message will cause immediate halt of the NGS program.  The
  167.     most probable causes are invalid command line or a corrupted Guides
  168.     database file.
  169.  
  170.      1. Error: Unknown command line option.  See usage.
  171.  
  172.      2. Error: Multiple filename specified.  See usage.
  173.  
  174.      3. Error: Filename with .NG extension is expected.
  175.  
  176.      4. Error: Specified file cannot be found
  177.  
  178.      5. Error: NG file is corrupted (File is too small to be an NG file)
  179.  
  180.      6. Error: NG file is corrupted (Missing signature)
  181.  
  182.      7. Error: NG file is corrupted (Menu count <1 or >10)
  183.  
  184.      8. Error: NG file is corrupted (Menu ite